Working with the API
- The API is only distributed as a "release" (a.k.a. "retail") build i.e. there is no debug information, symbol files etc.
- For projects using the API, add these entries to Configuration Properties (right-click on the project in Solution Explorer and select "Properties"), where [the API install path] is the folder containing the API SDK:
- The API’s main simulation functions are in the LegionSimulator and LegionSimulatorSupport libraries. Headers for types and functions are installed here:
- License support and query functions are provided through LegionLicenceSupport, headers are here:
- The API’s types and functions typically reside in the Legion::Simulator and Legion::Model namespaces. Please review the examples in Test Bench to see how the API’s types and functions are used to create and run LEGION simulations.
- Applications built with the API will require LEGION Simulator API entitlement while executing simulation functions. When running your applications, you must either:
-
To use the API’s LEGION Simulation functions, your application
must create an instance of
ISimulator (declared in the
Legion::Simulator namespace).
Creating an ISimulator instance consumes CONNECT licenses for LEGION Simulator API and LEGION Simulator products.
-
The Test Bench shows how to do this in the
BasicSimulator.hpp file’s
BeginExample() method.
The exact code is:
std::string sProductName_In = "LEGION Simulator API"; // Must be exactly this string (case-sensitive) to use LEGION Simulator API std::string sProductVersion_In = Legion::LicenceSupport::CLegnLicenceSupport::GetProductVersion().AsString(); // Must match the current API version - use Licence Support function to ensure this Legion::LicenceSupport::Simulator_API_ConnectionString::SimAPIPublicKeyPtr pPublicKey_Out; // Licence connection’s public encryption key goes here - use this to create a Licence Support instance for // querying licence information std::string sConnectionString_Out; // Encrypted licence connection string goes here - use this when querying licence information auto pSimulator = Legion::Simulator::CLegionSimulatorFactory::CreateSimulator( hAssociatedWindow_IN, sProductName_In, sProductVersion_In, pPublicKey_Out, sConnectionString_Out ); // This creates a Legion::Simulator::ISimulatorPtr instance; LEGION simulation functions are mostly accessed through here // A valid, non-null window handle (associatedWindow) is a required parameter. // If window handle is null, CreateSimulator will fail.
- Note the use of the CLegionSimulatorFactory::CreateSimulator method to create an ISimulator instance.
- LEGION simulator instance is encapsulated in a smart pointer of type Legion::Simulator::ISimulatorPtr.
- Correct required parameters will yield a valid Legion::Simulator::ISimulatorPtr instance.
- If the licence parameters are incorrect, a licence exception is thrown, and the ISimulatorPtr instance is not created.
- To use license-query functions, always create a new public key for encrypting the license connection string.
-
You should never reuse the key and connection string used to
initialise the Simulator; doing so will result in an RSA exception:
InvertibleRSAFunction: computational error during private key operation
- To avoid this exception, always generate a new public key and connection string before calling license-query functions, as is shown in the release notes’ Querying Licence Information topic.
- You only need to create the public key and connection string once for calling these functions.
-
The Test Bench shows how to do this in the
BasicSimulator.hpp file’s
BeginExample() method.